/*
 * 	<pre>
 *	EasyPeas.
 *  Copyright (C) 2007 S Owen
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 * Jul 24, 2007
 * Mappings.java
 * </pre>
 */
package org.easypeas.mappings;

import java.lang.reflect.Method;
import org.easypeas.exceptions.ForwardNotFoundException;

/**
 * Defines an interface to the mappings between Objects, views, forwards,
 * actions and accessors. How these mappings are discovered is determined by the
 * implementation.
 * 
 * @see MappingsFactory
 * 
 * @author S Owen
 * 
 */
public interface Mappings {

	/**
	 * Returns an instance of an Object that has annotated with the
	 * EasyPea annotation with the provided name.
	 * 
	 * Returns null if no Object is mapped to this key.
	 * 
	 * @param name
	 *            the name
	 * 
	 * @return the object
	 * @see EasyPea
	 */
	Object getObject(String name);

	/**
	 * Returns the name attribute of the EasyPea annotation for the
	 * given Object, otherwise null.
	 * 
	 * @param obj
	 *            the object
	 * 
	 * @return the name
	 * @see EasyPea
	 */
	String getName(Object obj);

	/**
	 * Returns the forward for the given Object and method and forward name
	 * returned from an Action annotation.
	 * 
	 * @param obj
	 *            the object
	 * @param method
	 *            the method
	 * @param forwardName
	 *            the forwardName
	 * 
	 * @return the forward
	 * 
	 * @throws ForwardNotFoundException
	 *             if no matching forward has been defined by the annotation.
	 * @see Action
	 */
	String getForward(Object obj, String method, String forwardName)
			throws ForwardNotFoundException;

	/**
	 * Returns the Method mapped to a given EasyPea annotated Object and
	 * annotated Action name.
	 * 
	 * @param obj
	 *            the EasyPea object
	 * @param name
	 *            the name
	 * 
	 * @return the action Method
	 * 
	 * @throws NoSuchMethodException
	 *             if no matching action is found.
	 * @see EasyPea
	 * @see Action
	 */
	Method getAction(Object obj, String name) throws NoSuchMethodException;

	/**
	 * Returns the Method mapped to a given EasyPea annotated Object and annotated View
	 * name.
	 * 
	 * @param obj
	 *            the EasyPea Object
	 * @param name
	 *            the name
	 * 
	 * @return the view Method
	 * 
	 * @throws NoSuchMethodException
	 *             if no matching view is found.
	 * @see EasyPea
	 * @see View
	 */
	Method getView(Object obj, String name) throws NoSuchMethodException;

	/**
	 * Returns the Method mapped to a given EasyPea annotated Object and annotated Accessor
	 * name.
	 * 
	 * @param obj
	 *            the EasyPea Object
	 * @param name
	 *            the name
	 * 
	 * @return the accessor Method
	 * 
	 * @throws NoSuchMethodException
	 *             if no matching accessor is found.
	 * @see EasyPea
	 * @see Accessor
	 */
	Method getAccessor(Object obj, String name) throws NoSuchMethodException;

	/**
	 * Returns the template to be used to process the results of a View annotated method
	 * based on the provided view Methods overridden template.
	 * 
	 * @param method
	 *            the method
	 * 
	 * @return the view template
	 * @see View
	 */
	String getViewTemplate(Method method);
}
